Bevy system error handling
Decorate your bevy system with the sysfail
macro attribute to handle failure.
Before
use *;
use Duration;
use Error;
After
use *;
use *;
use Error;
sysfail
attribute
sysfail
is an attribute macro you can slap on top of your systems to define
the handling of errors. Unlike pipe
, this is done directly at the definition
site, and not when adding to the app. As a result, it's easy to see at a glance
what kind of error handling is happening in the system, it also allows using
the system name as a label in system dependency specification.
The sysfail
attribute can only be used on systems returning a type
implementing the Failure
trait. Failure
is implemented for
Result<(), impl FailureMode>
and Option<()>
.
sysfail
takes a single argument, it is one of the following:
log
: print theErr
of theResult
return value, prints a very generic "A none value" when the return type isOption
. By default, most things are logged atWarn
level, but it is possible to customize the log level based on the error value.log(level = "{silent,trace,debug,info,warn,error}")
: This forces logging of errors at a certain level (make sure to add the quotes)ignore
: This is likelog(level="silent")
but simplifies the generated code.
Note that with log
, the macro generates a new system with additional
parameters.
quick_sysfail
attribute
quick_sysfail
is like sysfail(ignore)
but only works on Option<()>
.
This attribute, unlike sysfail
allows you to elide the final Some(())
and the type signature of the system. It's for the maximally lazy, like
me.
use *;
// equivalent to:
Traits
How error is handled is not very customizable, but there is a few behaviors controllable by the user, always through traits.
Failure
trait
Failure
is implemented for Result<(), impl FailureMode>
and Option<()>
.
Systems marked with the sysfail
attribute must return a type implementing
Failure
.
FailureMode
trait
FailureMode
defines how the failure is handled. By implementing the
trait on your own error types, you can specify:
-
What constitutes "distinct" error types.
-
The log level of specific values.
-
How long an error must not be produced in order to be displayed again.
-
TODO: provide a derive macro that allows setting log level and cooldown.
FailureMode
is implemented for Box<dyn Error>
, anyhow::Error
, ()
and &'static str
.
LogLevelOverride
trait
LogLevelOverride
is an extension trait that allows you to override the
log level of a failure. Use the warn
, trace
, debug
, silent
,
error
and info
methods to specify the level of logging of a failure.
Change log
1.0.0
: Update to bevy0.9
1.1.0
: Allow usage of mutable queries (oops)2.0.0
: Breaking: Update to bevy0.10
3.0.0
: Breaking: Update to bevy0.11
Version Matrix
bevy | latest supporting version |
---|---|
0.11 | 3.0.0 |
0.10 | 2.0.0 |
0.9 | 1.1.0 |
0.8 | 0.1.0 |
License
Copyright © 2022 Nicola Papale
This software is licensed under Apache 2.0.